클로드 코드 완벽 가이드 — 6장 CLAUDE.md 파일에 대한 모든 것 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

6장에서 다루는 내용

• CLAUDE.md란 무엇인가 — 클로드 코드에게 프로젝트 맥락을 전달하는 핵심 설정 파일
• CLAUDE.md에 어떤 정보를 입력해야 하는가 — 효과적인 내용 구성 전략
• CLAUDE.md 파일 종류 3가지 — 프로젝트/로컬/사용자 메모리 용도별 구분
• CLAUDE.md 파일 관리 노하우 — 실시간 수정, 주기적 관리, 정리 요청 기법
• 클로드 코드의 CLAUDE.md 읽기 방식 — 재귀적으로 루트까지 거슬러 올라가며 읽기

전체 흐름도

[CLAUDE.md 개념]            [작성법]                [관리 노하우]
    |                        |                        |
    v                        v                        v
+------------------+  +--------------------+  +---------------------+
| CLAUDE.md란?     |  | 어떤 정보를 넣을까? |  | 실시간 수정 (#키)    |
| = 프로젝트 브리핑 |  | • bash 명령어       |  | • # 키로 즉시 추가   |
|   문서            |  | • 핵심 파일/함수    |  | • 저장 위치 3가지 선택|
|                  |  | • 코드 스타일       |  |                     |
| LLM은 Stateless  |  | • 테스트 지침       |  | 주기적 관리          |
| → 매번 새 팀원   |  | • 저장소 에티켓     |  | • 대화 기반 추천 요청 |
| → CLAUDE.md로    |  | • 개발자 환경 설정  |  | • 클로드에게 위임    |
|   완벽한 팀원!    |  | • 라이브러리/아키텍처|  |                     |
+------------------+  +--------------------+  | 정리 요청            |
    |                                          | • 과도한 내용 축소   |
    v                                          | • /compact 활용      |
+------------------+                           +---------------------+
| 파일 종류 3가지  |
| 1. ./CLAUDE.md   | ← 프로젝트 메모리 (팀 공유)
| 2. ./claude.local.md | ← 로컬 메모리 (개인용, .gitignore)
| 3. ~/.claude/CLAUDE.md | ← 사용자 메모리 (전역 설정)
+------------------+
    |
    v
+------------------+
| 읽기 방식         |
| 현재 위치 → 루트  |
| 까지 거슬러 올라  |
| 가며 모두 읽음    |
| (재귀적 특성)     |
+------------------+

선수 지식 체크리스트

• [ ] 클로드 코드 설치 및 기본 사용법 (3장)
• [ ] 마크다운(Markdown) 기초 문법 (#, -, ** 등)
• [ ] Git 기본 개념 (.gitignore, 커밋 등)
• [ ] 프로젝트 폴더 구조 개념

핵심 키워드

6.1 CLAUDE.md란 무엇인가?

한 줄 요약

CLAUDE.md는 클로드 코드에게 프로젝트의 아키텍처, 코딩 규칙, 작업 절차를 알려주는 "브리핑 문서"로, 매번 설명 없이도 정확한 코드를 제안받을 수 있게 해준다.

쉬운 설명 (새 팀원 비유)

❌ CLAUDE.md 없이 클로드 코드 사용:
매번 새 팀원이 입사 → "이 프로젝트 뭐하는 거예요?"
→ 매번 처음부터 설명해야 함 → 비효율적!

✅ CLAUDE.md 있으면:
새 팀원에게 프로젝트 가이드라인 문서 전달
→ "아 이렇게 하면 되는군요!" → 바로 정확한 작업 시작!

LLM은 Stateless(상태 비저장)하기 때문에 매 요청이 독립적이다. 클로드 코드와 새 채팅을 시작하면 매번 새 팀원과 협업하는 것과 같다. 하지만 CLAUDE.md 파일이 있으면 이 구도가 완전히 달라진다 — 매번 프로젝트의 복잡한 내용을 반복 설명할 필요가 없다.

실무 예제 — CLAUDE.md 기본 형태

# CLAUDE.md
이 파일은 이 저장소의 코드 작업을 할 때 Claude Code(claude.ai/code)에 대한 지침을 제공합니다.

# 프로젝트 개요
이 프로젝트는 Next.js 15.2.4와 React 19로 구축된 암호화폐 순위 대시보드입니다.
가격, 시가 총액, 거래량 및 24시간 변동을 포함하여 상위 암호화폐에 대한
실시간 정보를 표시합니다.

포인트: 특별한 구조가 없어도 된다. #로 제목을 구분하고 자연어로 명확한 지시만 해두면 클로드 코드가 문맥을 이해한다.

핵심 체크포인트

• [ ] CLAUDE.md는 프로젝트 루트에 위치하는 마크다운 파일이다
• [ ] 클로드 코드는 이 파일을 읽어 프로젝트 맥락을 파악한 뒤 더 정확한 코드를 제안한다
• [ ] LLM의 Stateless 특성을 보완하는 "영구 메모리" 역할을 한다

6.2 CLAUDE.md는 어떻게 작성해야 하는가?

한 줄 요약

로 제목을 구분하고, 자연어로 명확한 지시를 작성하면 된다 — 특별한 구조보다 "명확한 지시"가 핵심이다.

쉬운 설명 (주니어 개발자 비유)

CLAUDE.md 작성 = 주니어 개발자에게 요구사항 전달하는 것

❌ "알아서 잘 해줘" → 뭘 어떻게 하라는 건지 모름
✅ "테이블은 tanstack table, 폼은 tanstack form 사용해" → 바로 정확히 작업!

포맷 가이드

실무 예제 — 기술 스택과 아키텍처 명시

# 사용할 기술 정리
- **테이블 제작할 때** 꼭 tanstack table 사용
- **폼 제작할 때** 꼭 tanstack form 사용

# 프로젝트 아키텍처
app/
├── (public)/           # 공개 라우트
│   ├── login/
│   ├── register/
│   └── profile/
├── admin/              # 어드민 대시보드
└── api/                # API 라우트
    ├── admin/v1/       # 어드민 API
    └── public/v1/      # 공개 API

이렇게 라이브러리와 아키텍처를 명시해두면 클로드 코드가 라이브러리를 찾느라 헤매지 않고, 아키텍처를 준수하여 코드를 작성한다.

핵심 체크포인트

• [ ] # 제목으로 섹션을 구분하고 자연어로 지시를 작성한다
• [ ] 강조 표현(IMPORTANT, YOU MUST)을 사용하면 클로드 코드가 해당 지시를 더 잘 지킨다
• [ ] 라이브러리와 아키텍처 정보를 명시하면 코드 품질이 크게 올라간다

6.3 CLAUDE.md에 어떤 정보를 입력해야 할까?

한 줄 요약

자주 쓰는 bash 명령어, 핵심 파일, 코드 스타일, 테스트 지침, 저장소 에티켓, 개발 환경 설정, 예외 동작 등 "반복 설명이 필요한 것"만 넣는다.

쉬운 설명 (냉장고 비유)

CLAUDE.md = 냉장고 (콘텍스트 윈도우 200K가 용량 한계)

❌ 냉장고에 모든 식재료를 넣으면 → 문이 안 닫힘 (콘텍스트 오버플로)
✅ 자주 쓰는 식재료만 넣으면 → 효율적으로 요리 가능!

→ 꼭 필요한 내용만 입력해야 클로드 코드가 실질적 문제 해결에 콘텍스트를 쓸 수 있다

앤트로픽 권장 입력 항목

핵심 체크포인트

• [ ] 콘텍스트 윈도우(200K)는 유한하므로 꼭 필요한 내용만 입력한다
• [ ] 불필요한 내용을 넣으면 오히려 클로드 코드의 문제 해결 능력이 떨어진다
• [ ] "반복해서 설명하게 되는 것"이 CLAUDE.md에 넣을 후보이다

6.4 CLAUDE.md 파일 종류 3가지

한 줄 요약

프로젝트 메모리(./CLAUDE.md), 로컬 프로젝트 메모리(./claude.local.md), 사용자 메모리(~/.claude/CLAUDE.md)로 용도별 3가지 파일을 사용한다.

쉬운 설명 (회사 규칙 비유)

사용자 메모리 (~/.claude/CLAUDE.md)
= 내 개인 업무 스타일 (어떤 회사에서든 적용)
  예: "항상 2칸 들여쓰기", "vim 키바인딩 사용"

프로젝트 메모리 (./CLAUDE.md)
= 팀 공통 규칙 (이 프로젝트의 모든 팀원이 따름)
  예: "React 19 사용", "테이블은 tanstack table"

로컬 프로젝트 메모리 (./claude.local.md)
= 내 책상 위 메모 (나만 보는 설정)
  예: "내 샌드박스 URL", "개인 API 키"

3가지 파일 비교표

실무 판단 기준

Q: 이 설정을 어디에 저장해야 할까?

프로젝트 전반 + 팀과 공유 → ./CLAUDE.md
프로젝트 관련 + 개인만 사용 → ./claude.local.md
모든 프로젝트 + 내 취향 → ~/.claude/CLAUDE.md

핵심 체크포인트

• [ ] 팀과 공유할 프로젝트 규칙은 ./CLAUDE.md에 저장한다
• [ ] 개인 설정(API 키, 샌드박스 URL)은 ./claude.local.md에 저장하고 .gitignore에 추가한다
• [ ] 모든 프로젝트에 적용할 개인 스타일은 ~/.claude/CLAUDE.md에 저장한다

6.5 CLAUDE.md 파일 관리 노하우

한 줄 요약

CLAUDE.md는 한 번 작성하고 끝이 아니라, # 키로 실시간 수정하고, 클로드 코드에게 주기적으로 관리/정리를 맡겨야 한다.

쉬운 설명 (정원 관리 비유)

CLAUDE.md = 정원

❌ 한 번 심고 방치 → 잡초(불필요한 내용)가 무성해짐
✅ 주기적으로 가꾸기 → 항상 깔끔하고 효율적!

관리 방법 3가지:
1. 실시간 수정 (#키) — 필요할 때 즉시 추가
2. 주기적 관리 — 대화 끝날 때 클로드에게 추천 요청
3. 정리 요청 — 파일이 커지면 클로드에게 축소 요청

관리 기법 1: # 키로 실시간 수정

클로드 코드 실행 중에 # 키를 눌러 지시를 내리면 CLAUDE.md 파일에 자동으로 통합된다.

입력: # 변수 이름은 항상 카멜 케이스로 작성해 줘

→ 저장 위치 선택 화면:
  1. Project memory       → ./CLAUDE.md (커밋에 포함)
  2. Project memory (local) → ./claude.local.md (.gitignore)
  3. User memory          → ~/.claude/CLAUDE.md (전역)

팁: CLAUDE.md에 변경 사항이 생기면 커밋에 포함시켜 팀원들도 혜택을 볼 수 있도록 한다.

관리 기법 2: 클로드 코드에게 주기적으로 관리시키기

프롬프트 예시:
"지금까지의 대화를 기반으로 CLAUDE.md에 추가할 만한 내용을 추천해줘"

→ 클로드 코드가 대화 내용을 분석하여 CLAUDE.md에 추가할 항목을 제안
→ 내용을 확인한 다음 추가

관리 기법 3: 클로드 코드에게 정리 요청하기

CLAUDE.md가 과도하게 커지면 정리를 요청한다.

프롬프트 예시:
"CLAUDE.md 파일이 너무 커지고 있는 것 같아.
프로젝트를 전반적으로 다시 이해하고 CLAUDE.md에 필요 없는 내용은 삭제하고
과도한 내용은 축소하고 싶어. 수정된 내용을 추천해줘."

→ 클로드 코드가 간소화된 CLAUDE.md 추천

강조 표현의 힘

❌ 일반 지시: "변수명은 카멜 케이스로 작성하세요"
✅ 강조 지시: "IMPORTANT: 변수명은 반드시 카멜 케이스로 작성해야 합니다"
    또는: "YOU MUST use camelCase for all variable names"

→ 강조하면 클로드 코드가 /compact로 압축할 때도 해당 내용이 살아남을 가능성이 높아진다

핵심 체크포인트

• [ ] # 키로 실행 중 즉시 CLAUDE.md에 내용을 추가할 수 있다
• [ ] 대화 끝날 때 클로드에게 CLAUDE.md 추가 추천을 요청하면 효율적이다
• [ ] 파일이 과도하게 커지면 클로드에게 정리를 요청한다
• [ ] IMPORTANT, YOU MUST 등 강조 표현을 사용하면 지시 준수율이 높아진다

6.6 클로드 코드는 CLAUDE.md 파일을 어떻게 읽을까?

한 줄 요약

클로드 코드는 현재 프로젝트 위치에서 루트 디렉터리까지 거슬러 올라가며 모든 CLAUDE.md 파일을 재귀적으로 읽는다.

쉬운 설명 (엘리베이터 비유)

클로드 코드의 CLAUDE.md 읽기 = 건물 1층까지 엘리베이터 타기

현재 위치: /abc/123 프로젝트 (5층)
    ↑ /abc/123/CLAUDE.md 읽음
    ↑ /abc/CLAUDE.md 읽음 (상위 폴더)
    ↑ 루트까지 계속 올라감

→ 모든 층의 CLAUDE.md를 다 읽는다!

재귀적 읽기의 실무 활용

/abc/
├── CLAUDE.md           ← 공통 규칙 (웹 + iOS + 안드로이드)
├── 123/ (웹 프로젝트)
│   └── CLAUDE.md       ← 웹 전용 규칙
└── 456/ (모바일 프로젝트)
    └── CLAUDE.md       ← 모바일 전용 규칙

/abc/123에서 클로드 코드 실행 시:
→ /abc/123/CLAUDE.md + /abc/CLAUDE.md 둘 다 읽힘

장점: 같은 서비스의 웹/모바일 프로젝트가 공통 규칙을 공유하면서
      각자 고유한 규칙도 가질 수 있다

핵심 체크포인트

• [ ] 클로드 코드는 현재 위치에서 루트까지 거슬러 올라가며 모든 CLAUDE.md를 읽는다
• [ ] 이 재귀적 특성 덕분에 큰 프로젝트(모노레포)에서 공통 규칙과 개별 규칙을 분리하여 관리할 수 있다
• [ ] 연관된 여러 프로젝트가 상위 폴더의 CLAUDE.md를 공유할 수 있다

연습 문제

문제 1: CLAUDE.md 작성 실습

다음 조건의 프로젝트에 맞는 CLAUDE.md를 작성해보세요. - Next.js 14 + TypeScript 프로젝트 - Tailwind CSS 사용 - Jest로 테스트 - ESLint + Prettier 적용

# CLAUDE.md

# 프로젝트 개요
Next.js 14와 TypeScript로 구축된 웹 애플리케이션입니다.

# 기술 스택
- **프레임워크**: Next.js 14 (App Router)
- **언어**: TypeScript
- **스타일링**: Tailwind CSS
- **테스트**: Jest + React Testing Library

# 코딩 규칙
- IMPORTANT: 모든 컴포넌트는 TypeScript로 작성
- YOU MUST: Tailwind CSS 클래스만 사용 (인라인 스타일 금지)
- 변수명은 카멜 케이스, 컴포넌트명은 파스칼 케이스

# 자주 사용하는 명령어
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`

문제 2: 파일 종류 판단 실습

아래 각 설정을 어떤 CLAUDE.md 파일에 저장해야 하는지 판단해보세요.

1. "이 프로젝트는 Python 3.12와 FastAPI를 사용한다"
2. "내 개인 샌드박스 서버 URL은 https://my-sandbox.dev 이다"
3. "나는 모든 프로젝트에서 2칸 들여쓰기를 선호한다"
4. "이 프로젝트의 브랜치 전략은 Git Flow이다"
5. "내 로컬 테스트용 API 키는 sk-test-1234이다"

문제 3: CLAUDE.md 정리 실습

아래 CLAUDE.md가 과도하게 길어졌습니다. 핵심만 남기고 정리해보세요.

# 프로젝트
이 프로젝트는 2024년 1월에 시작했고 김철수, 이영희, 박민수가 참여했습니다.
처음에는 React 17을 썼다가 18로 업그레이드 했고 지금은 19입니다.
CSS는 처음에 styled-components를 썼는데 Tailwind로 바꿨습니다.
데이터베이스는 MySQL에서 PostgreSQL로 마이그레이션 했습니다.
서버는 Express에서 Fastify로 변경했습니다.
작년 12월에 있었던 버그는 해결되었습니다.

# 기술 스택
- 프론트엔드: React 19 + Tailwind CSS
- 백엔드: Fastify
- 데이터베이스: PostgreSQL

부록 A: 용어 사전

부록 B: 비교표

CLAUDE.md 파일 종류별 비교

CLAUDE.md 있을 때 vs 없을 때

부록 C: 참고 자료